Composition Jobs (.wacj)

A WebWorks AutoMap Composition Job is a small XML file with the .wacj extension, run by the same AutoMap application that runs .waj job files. It lists the member jobs, the site table of contents, and the shared output destination:

<?xml version="1.0" encoding="utf-8"?>
<CompositionJob name="product-docs" version="1.0">
  <Jobs target="Web Help">
    <Job path="shell\shell.waj"       role="shell"/>
    <Job path="install\install.waj"   role="parcel"/>
    <Job path="admin\admin.waj"       role="parcel"/>
  </Jobs>

  <MergeSettings>
    <Group name="Installation Guide"/>
    <Group name="Administration Guide"/>
  </MergeSettings>

  <Destination name="ProductionSite"/>
</CompositionJob>

Members

Each <Job> references a member job (.waj) or project (.wep) and marks its role as shell or parcel. By default the composition does not rebuild members — their output is already deployed. Add build="true" to a member to have the composition build and deploy it first, in its own process, with the deploy scope set automatically from its role and the destination set to the composition's own. A built member therefore publishes where the composition publishes, whatever destination its own job declares.

Federated and derivative compositions

The build flag on each member is the seam between two ways of running a composition. Leave it off and the member is federated: its own job builds and deploys it on its own schedule, and the composition only assembles what it finds already deployed. Turn it on and the composition is derivative: it builds that member itself and deploys it to its own destination. A composition whose members are all built is self-contained — the member jobs supply the content (their documents, targets, conditions, variables, and placement) while the composition owns the build, the deploy scope, and the destination — so one command republishes the whole site. One composition can mix both kinds, member by member. Compositions created in ePublisher AutoMap add new members with Build selected; a composition written by hand leaves it off unless the attribute is present.

Output target

The target attribute on <Jobs> names the output target that every member builds and composes through. A target attribute on an individual <Job> overrides it for that member, which is how a federation spans teams whose targets are named differently. Omit both attributes and each member's output target is detected automatically. Selection is always made from the target list the member itself declares — the targets in a job file (preferring the ones the job marks to build) or the targets in a project — so a composition never reaches past what a member says it produces. Detection succeeds when exactly one of those targets uses a format that supports composition, and reports an error listing the candidates when more than one does. However the target is chosen, every member must produce the same output format — target names can vary from member to member, formats cannot, and a mismatch stops the run before any member builds.

Merge Settings

The <MergeSettings> element declares the composed site table of contents. Each <Group name="…"/> names a deployed parcel group; wrap groups in <TOC name="…"> elements to nest them under folders. Alternatively, add discover="true" to compose every parcel found in the destination without listing them — new parcels appear in the site as soon as they are deployed and the composition reruns.

Tolerance

A declared group with no deployed parcel is reported as a warning and omitted; the composed site loads cleanly with the parcels that are present. Composing again after the missing parcel deploys completes the site.

Running a composition takes seconds, because nothing is rebuilt:

WebWorks.Automap.exe product-docs.wacj

Note: Group names are the durable identity in a federation. Parcels' internal group IDs regenerate across rebuilds and re-stagings, and the composition resolves them automatically from the deployed records — always reference parcels by group name in Merge Settings.